jsonDecode

Type

function

Summary

Converts a string containing JSON to a LiveCode value.

Syntax

jsonDecode(<json>)

Description

Use the jsonDecode function to convert a string containing JSON to a LiveCode value.

Converting JSON to a LiveCode value works by decoding the provided string and building a LiveCode value which matches it faithfully.

The value returned by jsonDecode will depend on the JSON values encountered and strict type operators can be used to determine the exact type of JSON value.

If a JSON null value is encountered, the LiveCode value will be nothing and is strictly a nothing.

If a JSON true or JSON false value is encountered, the LiveCode value will be true or false and is strictly a boolean.

If a JSON number value is encountered, the LiveCode value will be a number and is strictly a number.

If a JSON string value is encountered, the LiveCode value will be a string and is strictly a string.

If a JSON array value is encountered, the LiveCode value will be a sequence array and is strictly a sequence.

If a JSON object value is encountered, the LiveCode value will be a dictionary array and is strictly a dictionary.

The additional information provided by the strict types can be useful when dealing with JSON generated by other environments where typing matters.

If the provided JSON is found to be invalid during the decoding process, the function returns nothing and the result is set to a string describing the error.

The error string has three items "token-start,token-finish,error".

The token-start and token-finish items are the char indices in the provided string covering the characters causing the problem.

The error item describes what caused the error:

• no input: JSON has been provided which is entirely whitespace and contains no value.
• unexpected char: a character has been encountered which cannot start a JSON token.
• invalid null: the start of a null token was encountered, but was not complete.
• invalid false: the start of a false token was encountered, but was not complete.
• invalid true: the start of a true token was encountered, but was not complete.
• unterminated string: the end of the JSON was encountered while still decoding a string.
• unescaped control char: an ASCII control character (one which has codepoint < 32) was encountered in a string but has not been escaped.
• incomplete escape: the end of the JSON was encountered after a backslash character in a string.
• invalid escape char: a character following a backslash character in a string was not one representing an escape.
• incomplete unicode escape: the end of input was encountered before four hexadecimal digits were encountered after a unicode escape.
• invalid unicode escape: less than the required four hexademical digits were encountered after a unicode escape.
• integer expected: no digit was encountered after a - character at the start of a number token.
• fraction expected: no digit was encountered after a . character inside a number token.
• exponent expected: an invalid character was encountered after an e character inside a number token.
• root value expected: an invalid token was encountered when decoding the top-level value.
• value or right bracket expected: an invalid token was encountered before decoding the first element of a JSON array.
• comma or right bracket expected: an invalid token was encountered after decoding a JSON array element.
• element value expected: an invalid token was encountered when expecting another JSON array element.
• string or right brace expected: an invalid token was encountered before decoding the first member of a JSON object.
• comma or right brace expected: an invalid token was encountered after decoding a member of a JSON object.
• string expected: an invalid token was encountered when expecting another JSON object member.
• colon expected: an invalid token was encountered after decoding the key part of a member of a JSON object.
• member value expected: an invalid token was encountered when expecting a JSON object member value.
• whitespace expected: further tokens were encountered after finishing decoding the top-level value.

note

The jsonDecode function implements JSON syntax exactly as described at https://www.json.org. If the provided JSON does not match the format described there, the function will fail with one of the errors listed above.

Parameters

Name	Type	Description
json		The string to be converted from JSON format to a LiveCode value. Returns; The jsonDecode function returns a LiveCode value matching that represented by the provided JSON.

Examples

jsonDecode("null") is strictly nothing -- returns true

jsonDecode("true") is strictly true -- returns true

jsonDecode("false") is strictly false -- returns true

jsonDecode(quote & "Hello World" & quote) is "Hello World" -- returns true

jsonDecode("[]") is strictly [] -- returns true

jsonDecode("{}") is strictly {} -- returns true

the number of elements in jsonDecode("[1, 2, 3]") -- returns 3

Related

operator: is a, is strictly a, as a

function: jsonEncode

Compatibility and Support

Introduced

LiveCode Create 1.0

OS

mac

windows

linux

ios

android

web

Platforms

desktop

server

mobile